docs(freeticket-cli): settlements/api-keys + skill freeticket-mcp + el repo como plugin instalable - #13

• Document ft ≥ 0.9.0 commands: settlements, financial reports, API keys, and admin tokens.
• Clarify authoritative payout/financial workflow (reports financials → settlements list) and
 PDF limitations.
• Explain destructive-command confirmation behavior (TTY, exit codes) for safer scripting.

graph TD
  U["User / CI script"] --> CLI["ft CLI"] --> V1[["B2B API v1"]] --> FIN["Financials & settlements"]
  U --> CLI --> KEYS["API keys (ft_live)"]
  U --> CLI --> ADM[["Admin API"]] --> TOK["Admin tokens (PAT)"]

Loading

The following are alternative approaches to this PR:

1. Generate command reference from OpenAPI/CLI help output

• ➕ Reduces doc drift as new commands/flags ship
• ➕ Enables versioned docs aligned to CLI releases
• ➕ Lowers maintenance cost for large command surfaces
• ➖ Requires building and maintaining a docs-generation pipeline
• ➖ May miss nuanced guidance (e.g., payout interpretation, scripting caveats) unless supplemented

2. Add a “What’s new since X.Y” changelog section in docs

• ➕ Makes upgrades/behavior changes discoverable (e.g., exit codes, tokens)
• ➕ Smaller maintenance burden than full doc generation
• ➖ Still requires manual updates and can drift over time
• ➖ Doesn’t guarantee the main command tables stay complete

Recommendation: For immediate correctness, this PR’s manual updates are the right move because they add critical operational guidance (authoritative financial numbers, confirmation/TTY behavior) that auto-generated docs might omit. Longer-term, consider generating the command tables from the CLI/OpenAPI and keeping a small hand-written guidance layer to prevent future drift.

Documentation (2) +52 / -4

SKILL.mdBump minimum CLI version and document new financial/token workflows +19/-3

Bump minimum CLI version and document new financial/token workflows

• Updates the documented minimum 'ft' version to ≥ 0.9.0 and adds new commands ('reports financials', 'settlements list', 'api-keys', 'admin tokens'). Also clarifies destructive-command confirmation behavior (TTY + exit code 1 on abort) and explicitly directs money questions to 'reports financials'/'settlements' (including the panel-only proof PDF limitation).

skills/freeticket-cli/SKILL.md

commands.mdExpand CLI command reference with search, settlements/financials, and token/key sections +33/-1

Expand CLI command reference with search, settlements/financials, and token/key sections

• Adds '--q' support to 'ft events list' in the reads table and documents 'settlements list', 'reports financials', and 'api-keys list'. Introduces explanatory sections for settlements vs. financial reports, plus a dedicated service-credentials section for 'ft api-keys' and new admin token commands ('ft admin tokens list|create|revoke').

skills/freeticket-cli/references/commands.md

Description

skills/freeticket-cli/references/commands.md still says a revocable admin service token is
“coming”, but this PR also adds the ft admin tokens list|create|revoke commands, which contradicts
the earlier guidance and can mislead CI/auth setup. The docs also don’t state (based on the actual
CLI interface) how to provide the newly minted plaintext token to later ft admin … commands.

Code

skills/freeticket-cli/references/commands.md[R159-161]

+| `ft admin tokens list` | — (no pagination) | SUPER_ADMIN |
+| `ft admin tokens create` | `--data` (`{"name","expiresAt?"}`) — plaintext shown once | SUPER_ADMIN |
+| `ft admin tokens revoke <id>` | `--yes` to skip confirm | SUPER_ADMIN |

Evidence

The Admin section in commands.md still claims a revocable service token is future work, but the
same file now lists ft admin tokens list/create/revoke. SKILL.md also recommends minting an
admin token for CI without documenting how that token is then provided to the CLI.

skills/freeticket-cli/references/commands.md[126-132]
skills/freeticket-cli/references/commands.md[159-165]
skills/freeticket-cli/SKILL.md[123-129]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

### Issue description
The admin authentication section still frames service tokens as future work, but the same reference now documents `ft admin tokens …`. This creates contradictory guidance and also leaves out the critical “how to use the created token” step for headless `ft admin`.

### Issue Context
- The reference currently says tokens are “coming”, while listing the token commands.
- `SKILL.md` advises using `ft admin tokens create` for CI, but neither doc shows (per the real CLI contract/help) how the minted token is supplied to future admin commands.

### Fix Focus Areas
- skills/freeticket-cli/references/commands.md[126-138]
- skills/freeticket-cli/references/commands.md[159-165]
- skills/freeticket-cli/SKILL.md[123-129]
- skills/freeticket-cli/SKILL.md[137-138]

### What to change
1. Remove or rewrite the stale “MVP — a revocable service token replaces this …” wording so it matches the now-documented `ft admin tokens …` feature.
2. Add a short, **verified** snippet showing how the minted admin token is used for subsequent `ft admin` calls (confirm the exact env var / flag from the CLI’s actual behavior/help, then document that mechanism explicitly).

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools